<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Project storage as zipfile &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Integration with Google Drive" href="google-drive.html" />
    <link rel="prev" title="Testing" href="testing.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="project-storage-as-zipfile">
<span id="storage-as-zipfile"></span><h1>Project storage as zipfile<a class="headerlink" href="#project-storage-as-zipfile" title="Link to this heading">¶</a></h1>
<p>We allow the user to download a project as a zipfile, to allow
moving a project from one device to another.</p>
<section id="structure-of-zipfile">
<h2>Structure of zipfile<a class="headerlink" href="#structure-of-zipfile" title="Link to this heading">¶</a></h2>
<section id="version-identifier">
<h3>Version identifier<a class="headerlink" href="#version-identifier" title="Link to this heading">¶</a></h3>
<p>At root, the zipfile contains a file <code class="docutils literal notranslate"><span class="pre">version.json</span></code> which is a JSON
representation of an object with just one integer-valued property,
<code class="docutils literal notranslate"><span class="pre">pytchZipfileVersion</span></code>.  The file is encoded as UTF-8 (which will
coincide with ASCII because all characters are in its range).</p>
<p>The remainder of the zipfile is laid out according to the version
number stored there.</p>
</section>
</section>
<section id="pytch-zipfile-version-3">
<h2>Pytch zipfile version 3<a class="headerlink" href="#pytch-zipfile-version-3" title="Link to this heading">¶</a></h2>
<p>A version-3 Pytch zipfile is laid out along the lines of the following
example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>version.json
meta.json
code/code.json
assets/metadata.json
assets/files/banana.jpg
assets/files/whoosh.mp3
</pre></div>
</div>
<p>The format is the same as in version 2, with the following exceptions:</p>
<ul class="simple">
<li><p>The program is stored in the file <code class="docutils literal notranslate"><span class="pre">code/code.json</span></code> instead of the
file <code class="docutils literal notranslate"><span class="pre">code/code.py</span></code>.  The object represented in this file mirrors
the type <code class="docutils literal notranslate"><span class="pre">PytchProgram</span></code> in the TypeScript code; <a class="reference internal" href="#zipfile-code-representation"><span class="std std-ref">more detail
below</span></a>.</p></li>
<li><p>The asset metadata and files should be in “canonical” order;
<a class="reference internal" href="#zipfile-asset-ordering"><span class="std std-ref">more detail below</span></a>.</p></li>
</ul>
<section id="code-representation">
<span id="zipfile-code-representation"></span><h3>Code representation<a class="headerlink" href="#code-representation" title="Link to this heading">¶</a></h3>
<p>The program is stored in JSON in the file <code class="docutils literal notranslate"><span class="pre">code/code.json</span></code>.  The
object stored in this file should have exactly the following
properties:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">kind</span></code></dt><dd><p>One of the fixed strings <code class="docutils literal notranslate"><span class="pre">&quot;flat&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">&quot;per-method&quot;</span></code>, indicating
what kind of program this is.</p>
</dd>
</dl>
<p>The object should also have further properties depending on its
<code class="docutils literal notranslate"><span class="pre">kind</span></code>:</p>
<section id="flat-programs">
<h4><code class="docutils literal notranslate"><span class="pre">&quot;flat&quot;</span></code> programs<a class="headerlink" href="#flat-programs" title="Link to this heading">¶</a></h4>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">text</span></code></dt><dd><p>A string containing the user’s Python program code.</p>
</dd>
</dl>
</section>
<section id="per-method-programs">
<h4><code class="docutils literal notranslate"><span class="pre">&quot;per-method&quot;</span></code> programs<a class="headerlink" href="#per-method-programs" title="Link to this heading">¶</a></h4>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">program</span></code></dt><dd><p>An object of type <code class="docutils literal notranslate"><span class="pre">StructuredProgram</span></code>.  This contains information
on the actors (stage and sprites) of the program.  For each one, the
object stores that actor’s event-handlers (scripts); see the code
for details.  The order of actors is important, with the stage
always first.</p>
</dd>
</dl>
</section>
</section>
<section id="asset-ordering">
<span id="zipfile-asset-ordering"></span><h3>Asset ordering<a class="headerlink" href="#asset-ordering" title="Link to this heading">¶</a></h3>
<p>The order of the records in the <code class="docutils literal notranslate"><span class="pre">assets/metadata.json</span></code> file should
match the order of the asset files under <code class="docutils literal notranslate"><span class="pre">assets/files</span></code> in the
zipfile.  (Note that unzipping the file into your filesystem may or
may not preserve this order.)</p>
<p>The order should be as follows.</p>
<section id="id1">
<h4><code class="docutils literal notranslate"><span class="pre">&quot;flat&quot;</span></code> programs<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h4>
<p>The order dictates the order in which the assets appear in the “Images
and Sounds” pane.  The “flat” IDE has no capability to re-order
assets, and the order of assets in the “Images and Sounds” pane is not
relevant to the project’s behaviour, because the <code class="docutils literal notranslate"><span class="pre">Costumes</span></code> (etc.)
lists are explicit in the code.</p>
</section>
<section id="id2">
<h4><code class="docutils literal notranslate"><span class="pre">&quot;per-method&quot;</span></code> programs<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h4>
<p>The assets should be ordered as follows.</p>
<ul class="simple">
<li><p>First by actor, so all stage assets occur first, followed by all
assets belonging to the first sprite, then all those belonging to
the second sprite, etc.</p></li>
<li><p>Within each actor, all images should appear before all sounds.</p></li>
<li><p>Within each asset-kind, the order should be the order those costumes
(say) appear in the (implicit) list of costumes for that actor,
which is the same as the order the costumes have in the “Costumes”
tab for that actor.</p></li>
</ul>
</section>
</section>
</section>
<section id="pytch-zipfile-version-2">
<h2>Pytch zipfile version 2<a class="headerlink" href="#pytch-zipfile-version-2" title="Link to this heading">¶</a></h2>
<p>A version-2 Pytch zipfile is laid out along the lines of the following
example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>version.json
meta.json
code/code.py
assets/metadata.json
assets/files/banana.jpg
assets/files/whoosh.mp3
</pre></div>
</div>
<section id="metadata-and-project-python-code">
<h3>Metadata and project Python code<a class="headerlink" href="#metadata-and-project-python-code" title="Link to this heading">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">meta.json</span></code> file and the <code class="docutils literal notranslate"><span class="pre">code/code.py</span></code> files are as in
version 1.</p>
</section>
<section id="project-assets">
<h3>Project assets<a class="headerlink" href="#project-assets" title="Link to this heading">¶</a></h3>
<p>The asset files are stored in the <code class="docutils literal notranslate"><span class="pre">assets/files</span></code> directory, with
each asset having its own file.</p>
<p>As is also the case in version 1, the mime-type of an asset is
determined solely by the extension of its file.  So, for example, a
file called “banana.jpg” which actually contains MP3 data will cause
trouble.</p>
<p>Asset transforms are stored as JSON in the file
<code class="docutils literal notranslate"><span class="pre">assets/metadata.json</span></code>.  That JSON represents an array of objects,
each of which has <code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">transform</span></code> properties, as in this
example:</p>
<div class="highlight-json notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
<span class="w">  </span><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;name&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;banana.jpg&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;transform&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
<span class="w">      </span><span class="nt">&quot;targetType&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;image&quot;</span><span class="p">,</span>
<span class="w">      </span><span class="nt">&quot;originX&quot;</span><span class="p">:</span><span class="w"> </span><span class="mf">0.8138888888888889</span><span class="p">,</span>
<span class="w">      </span><span class="nt">&quot;originY&quot;</span><span class="p">:</span><span class="w"> </span><span class="mi">0</span><span class="p">,</span>
<span class="w">      </span><span class="nt">&quot;width&quot;</span><span class="p">:</span><span class="w"> </span><span class="mf">0.18611111111111112</span><span class="p">,</span>
<span class="w">      </span><span class="nt">&quot;height&quot;</span><span class="p">:</span><span class="w"> </span><span class="mf">0.4311526878964568</span><span class="p">,</span>
<span class="w">      </span><span class="nt">&quot;scale&quot;</span><span class="p">:</span><span class="w"> </span><span class="mf">0.36271937853059033</span>
<span class="w">    </span><span class="p">}</span>
<span class="w">  </span><span class="p">},</span>
<span class="w">  </span><span class="p">{</span>
<span class="w">    </span><span class="nt">&quot;name&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;whoosh.mp3&quot;</span><span class="p">,</span>
<span class="w">    </span><span class="nt">&quot;transform&quot;</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
<span class="w">      </span><span class="nt">&quot;targetType&quot;</span><span class="p">:</span><span class="w"> </span><span class="s2">&quot;audio&quot;</span>
<span class="w">    </span><span class="p">}</span>
<span class="w">  </span><span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>The metadata should include information on exactly the same set of
assets as are in the zipfile.  Some missing information might be
gracefully handled, e.g., a missing <code class="docutils literal notranslate"><span class="pre">transform</span></code> property is OK
because a default ‘no-op’ transform can be used.  Future versions of
this metadata structure might include other properties.</p>
</section>
</section>
<section id="pytch-zipfile-version-1">
<h2>Pytch zipfile version 1<a class="headerlink" href="#pytch-zipfile-version-1" title="Link to this heading">¶</a></h2>
<p>A version-1 Pytch zipfile is laid out along the lines of the following
example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>version.json
meta.json
code/code.py
assets/banana.jpg
assets/whoosh.mp3
</pre></div>
</div>
<section id="metadata">
<h3>Metadata<a class="headerlink" href="#metadata" title="Link to this heading">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">meta.json</span></code> file contains an object in JSON, with the following
properties.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>{
  &quot;projectName&quot;: &quot;Chase the banana!&quot;
}
</pre></div>
</div>
</section>
<section id="project-python-code">
<h3>Project Python code<a class="headerlink" href="#project-python-code" title="Link to this heading">¶</a></h3>
<p>The project’s Python code is stored in <code class="docutils literal notranslate"><span class="pre">code/code.py</span></code>, encoded as
UTF-8.</p>
</section>
<section id="id3">
<h3>Project assets<a class="headerlink" href="#id3" title="Link to this heading">¶</a></h3>
<p>The assets are stored in the <code class="docutils literal notranslate"><span class="pre">assets</span></code> directory, with each asset
having its own file.</p>
<p>The mime-type of an asset is determined solely by the extension of its
file.  So, for example, a file called “banana.jpg” which actually
contains MP3 data will cause trouble.</p>
</section>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">Webapp</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="index.html#top-level-routes">Top-level routes</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html#individual-aspects-of-design">Individual aspects of design</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>